import { applyDecorators, Type } from "@nestjs/common";
import { ApiExtraModels, ApiOkResponse, getSchemaPath } from "@nestjs/swagger";

import { BaseSuccessResponseVO } from "../vo/base-response.vo";

/**
 * 创建一个用于API分页响应的装饰器
 *
 * @template TModel - 继承自Type<any>的泛型模型类型
 * @param model - 用于分页数据的具体数据模型类型
 * @returns 返回一个组合装饰器，用于描述分页响应的API文档结构
 *
 * 该装饰器会生成一个包含分页信息和数据列表的响应结构，
 * 其中数据部分包含list(数据列表)、total(总数)、current(当前页码)、
 * size(每页数量)、pages(总页数)等分页相关字段
 */
export const ApiPageResponse = <TModel extends Type<any>>(model: TModel) => {
    return applyDecorators(
        // 注册额外的模型引用，确保BaseSuccessResponseVO和具体model都能在文档中正确引用
        ApiExtraModels(BaseSuccessResponseVO, model),
        // 配置成功的API响应结构
        ApiOkResponse({
            schema: {
                // 使用allOf组合BaseSuccessResponseVO基础响应结构和具体的分页数据结构
                allOf: [
                    {
                        $ref: getSchemaPath(BaseSuccessResponseVO)
                    },
                    {
                        properties: {
                            data: {
                                type: "object",
                                properties: {
                                    list: {
                                        type: "array",
                                        items: { $ref: getSchemaPath(model) }
                                    },
                                    total: { type: "number", example: 100, description: "总数" },
                                    current: { type: "number", example: 1, description: "当前页码" },
                                    size: { type: "number", example: 15, description: "每页数量" },
                                    pages: { type: "number", example: 10, description: "总页数" },
                                    extend: {
                                        type: "object",
                                        additionalProperties: true,
                                        description: "扩展字段，例如：其他业务需要的字段"
                                    }
                                },
                                required: ["list", "total", "current", "size", "pages"]
                            }
                        }
                    }
                ]
            }
        })
    );
};
